<html>
<head>
<title>NITF -- Advanced Driver Information</title>
</head>

<body bgcolor="#ffffff">

<h1>NITF -- Advanced Driver Information</h1>

The NITF (National Imagery Transmission Format) driver in GDAL includes a
number of advanced, and somewhat esoteric options not suitable for the
<a href="frmt_nitf.html">general end user documentation</a> for the driver.
This information is collected here, and is primarily aimed at developers and
advanced users.

<h2>CGM Segments</h2>

NITF files that have CGM data (that is segment type GR - graphics, or SY with
an STYPE value of 'C') will make that information available as metadata in the
CGM domain.  The returned metadata will look something like:

<pre>
  SEGMENT_COUNT=1
  SEGMENT_0_SLOC_ROW=25
  SEGMENT_0_SLOC_COL=25
  SEGMENT_0_SDLVL=2
  SEGMENT_0_SALVL=1
  SEGMENT_0_CCS_ROW=00025
  SEGMENT_0_CCS_COL=00025
  SEGMENT_0_DATA=\0!\0...
</pre>

The SLOC_ROW and SLOC_COL values are the placement of the CGM object relative
to the base (SALVL) image.  The CCS_ROW/COL values are relative to the common
coordinate system.  The _SDLVL is the display level.
The DATA is the raw CGM data with "backslash quotable" escaping
applied.  All occurrences of ASCII zero will be translated to '\0', and all
backslashes and double quotes will be backslashed escaped.  The
CPLUnescapeString() function can be used to unescape the data into binary
format using scheme CPLES_BackslashQuotable. <p>

Since GDAL 1.8.0, to add CGM data to a NITF image, you can pass creation options in the following format:

<pre>
  CGM=SEGMENT_COUNT=1
  CGM=SEGMENT_0_SLOC_ROW=25
  CGM=SEGMENT_0_SLOC_COL=25
  CGM=SEGMENT_0_SDLVL=2
  CGM=SEGMENT_0_SALVL=1
  CGM=SEGMENT_0_DATA=\0!\0...
</pre>

Notice that passing CGM as creation options will overwrite existing CGM segment read in the CGM metadata domain.
<p>

While GDAL does not support parsing or rendering CGM data, at least one user
has found the <a href="http://sk1project.org/modules.php?name=Products&product=uniconvertor">UniConverter</a>
library useful for this purpose.

<h2>Multi-Image NITF Files</h2>

NITF files with more than one image segment (IM) will present the image
segments as subdatasets.  Opening a multiple NITF file by filename will provide
access to the first image segment.  The subdataset metadata for a 3 image
NITF file might look like:<p>

<pre>
Subdatasets:
  SUBDATASET_1_NAME=NITF_IM:0:multi_image_jpeg_2.0.ntf
  SUBDATASET_1_DESC=Image 1 of multi_image_jpeg_2.0.ntf
  SUBDATASET_2_NAME=NITF_IM:1:multi_image_jpeg_2.0.ntf
  SUBDATASET_2_DESC=Image 2 of multi_image_jpeg_2.0.ntf
  SUBDATASET_3_NAME=NITF_IM:2:multi_image_jpeg_2.0.ntf
  SUBDATASET_3_DESC=Image 3 of multi_image_jpeg_2.0.ntf
</pre>

In this case opening "multi_image_jpeg_2.0.ntf" directly will give
access to "NITF_IM:0:multi_image_jpeg_2.0.ntf".  To open the others
use the corresponding subdataset names.  The Subdataset mechanism is
generic GDAL concept discussed in the
<a href="http://www.gdal.org/gdal_datamodel.html">GDAL Data Model</a>
document.<p>

<h2>Text Segments</h2>

NITF files that have text segments (that is segment type TX) will make that
information available as metadata in the TEXT domain.
The returned metadata will look something like:

<pre>
  HEADER_0=TE       00020021216151629xxxxxxxxxxxxxxxxxxxxxxxxxxx
  DATA_0=This is test text file 01.

  HEADER_1=TE       00020021216151629xxxxxxxxxxxxxxxxxxxxxxxxxxx
  DATA_1=This is test text file 02.

  HEADER_2=TE       00020021216151629xxxxxxxxxxxxxxxxxxxxxxxxxxx
  DATA_2=This is test text file 03.

  HEADER_3=TE       00020021216151629xxxxxxxxxxxxxxxxxxxxxxxxxxx
  DATA_3=This is test text file 04.

  HEADER_4=TE       00020021216151629xxxxxxxxxxxxxxxxxxxxxxxxxxx
  DATA_4=This is test text file 05.
</pre>

The argument to DATA_n
is the raw text of the n'th (zero based) text segment with no escaping of any
kind applied. <p>

Since GDAL 1.8.0, the TEXT segment header data is preserved in HEADER_n metadata item.

The CreateCopy() method on the NITF driver also supports creating
text segments on the output file as long as the input file has metadata
in the TEXT domain as defined above.<p>

Since GDAL 1.8.0, to add TEXT data to a NITF image, you can also pass creation options in the following format:

<pre>
  TEXT=HEADER_0=TE       00020021216151629xxxxxxxxxxxxxxxxxxxxxxxxxxx
  TEXT=DATA_0=This is test text file 01.
  TEXT=HEADER_1=TE       00020021216151629xxxxxxxxxxxxxxxxxxxxxxxxxxx
  TEXT=DATA_1=This is test text file 02.
</pre>

Notice that passing TEXT as creation options will overwrite existing text segment read in the TEXT metadata domain.

<h2>TREs</h2>

NITF files with registered (or unregistered?) extensions on the file header,
or the referenced image header will make them available in a raw form in
metadata via the TRE domain.  The TRE domain will hold one metadata item per
TRE which will have the name of the TRE as the name, and the data of the TRE
as the contents.  The data contents will be "backslash escaped" like CGM
data above. <p>

In case of multiple occurrences of the same TRE, the second occurrence will be
named "TRENAME_2", the third "TRENAME_3" where TRENAME is the TRE name.<p>

<pre>
Metadata (TRE):
  GEOPSB=MAPM  World Geodetic System 1984
               WGE World Geodetic System 1984
                   WE Geodetic
                      GEODMean Sea
                          MSL 000000000000000
                                                0000
  PRJPSB=Polar Stereographic
         PG2-00090.00000250000039.99999884000000000000000000000000000000
  MAPLOB=M  0598005958-000003067885.8-000002163353.8
</pre>

<h2>TREs as xml:TRE</h2>

Starting with GDAL 1.9.0, all TREs found in file and matching one of the
TRE description of the <a href="http://trac.osgeo.org/gdal/browser/trunk/gdal/data/nitf_spec.xml">nitf_spec.xml</a> in GDAL data directory will be reported
as XML content in the xml:TRE metadata domain.<p>

<pre>
Metadata (xml:TRE):
&lt;tres&gt;
  &lt;tre name="RSMDCA" location="des TRE_OVERFLOW"&gt;
    &lt;field name="IID" value="2_8" /&gt;
    &lt;field name="EDITION" value="1101222272-2" /&gt;
    &lt;field name="TID" value="1101222272-1" /&gt;
    &lt;field name="NPAR" value="06" /&gt;
    &lt;field name="NIMGE" value="001" /&gt;
    &lt;field name="NPART" value="00006" /&gt;
    &lt;repeated name="IMAGE" number="1"&gt;
      &lt;group index="0"&gt;
        &lt;field name="IID" value="2_8" /&gt;
        &lt;field name="NPARI" value="06" /&gt;
      &lt;/group&gt;
    &lt;/repeated&gt;
    &lt;field name="XUOL" value="-2.42965895449297E+06" /&gt;
    &lt;field name="YUOL" value="-4.76049894293300E+06" /&gt;
    &lt;field name="ZUOL" value="+3.46898407315533E+06" /&gt;
    &lt;field name="XUXL" value="+8.90698769551156E-01" /&gt;
    &lt;field name="XUYL" value="+2.48664813021570E-01" /&gt;
    &lt;field name="XUZL" value="-3.80554217799520E-01" /&gt;
    &lt;field name="YUXL" value="-4.54593996792805E-01" /&gt;
    &lt;field name="YUYL" value="+4.87215943350720E-01" /&gt;
    &lt;field name="YUZL" value="-7.45630553709282E-01" /&gt;
    &lt;field name="ZUXL" value="+0.00000000000000E+00" /&gt;
    &lt;field name="ZUYL" value="+8.37129879594448E-01" /&gt;
    &lt;field name="ZUZL" value="+5.47004172461403E-01" /&gt;
[...]
    &lt;repeated name="DERCOV" number="21"&gt;
      &lt;group index="0"&gt;
        &lt;field name="DERCOV" value="+5.77388827727787E+04" /&gt;
      &lt;/group&gt;
[...]
      &lt;group index="20"&gt;
        &lt;field name="DERCOV" value="+1.14369570920252E-02" /&gt;
      &lt;/group&gt;
    &lt;/repeated&gt;
  &lt;/tre&gt;
  &lt;tre name="RSMECA" location="des TRE_OVERFLOW"&gt;
[...]
  &lt;/tre&gt;
  &lt;tre name="RSMIDA" location="des TRE_OVERFLOW"&gt;
[...]
  &lt;/tre&gt;
  &lt;tre name="RSMPCA" location="des TRE_OVERFLOW"&gt;
[...]
  &lt;/tre&gt;
&lt;/tres&gt;
</pre>

<h2>Raw File / Image Headers</h2>

In some cases application may need to recover very specific information
from the image or file headers that isn't normally available as metadata.
In this case it is possible to query the "NITF_METADATA" metadata domain.
The complete file and image headers will be returned as metadata in base64
encoded format.  Something like:<p>

<pre>
Metadata (NITF_METADATA):
  NITFFileHeader=002213 TklURjAyLjAwMDEgICAgVTIxN0cwSjA...
  NITFImageSubheader=439 SU1NaXNzaW5nIElEMjUxNTI1NTlaTU...
</pre>

Note that the ascii encoded numeric values prefixing the base64 encoded
header is the length (decoded) in bytes, followed by one space.  <p>

</body>
</html>
